EVN OCR API

Objective

The Vietnam Electricity (EVN) OCR API authenticates the EVN bills by comparing user-entered data with text extracted from uploaded bill images.

Input	Output
An image or PDF file containing a user's EVN Bill	A list of detailed information extracted from the document

DID YOU KNOW?

Vietnam Electricity (EVN) is the national and the sole public power company in Vietnam.

API Endpoint

verifyEVN

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the complete information on the parameters used in the request body for the API calls:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
image1	The parameter accepts either an image or a pdf file containing the EVN Bill	Mandatory	Image(JPG,JPEG,PNG) or PDF File	Not Applicable
name	The parameter accepts the full name of the user	Mandatory	Data Type:String	Not Applicable
address	The parameter accepts the address of the user	Mandatory	Data Type:String	Not Applicable
amount	The parameter accepts the total amount after VAT	Mandatory	Data Type:String	Not Applicable
evnId	The parameter accepts the EVN ID of the user	Mandatory	Data Type:String	Not Applicable
fromDate	The parameter accepts the From Date of the EVN Bill	Mandatory	Data Type:String Format:DD/MM/YYYY or DD/MM	Not Applicable
toDate	The parameter accepts the To Date of the EVN Bill	Mandatory	Data Type:String Format:DD/MM/YYYY or DD/MM	Not Applicable

Sample Request

The following code shows a standard cURL request for the API:

curl --location --request POST 'https://apac.docs.hyperverge.co/v1/verifyEVN' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image1=@"<path_to_image>"' \
--form 'name="<Enter_name_on_card>"' \
--form 'address="<Enter_address_on_card>"' \
--form 'amount="<Enter_amount>"' \
--form 'evnId="<Enter_evn_id>"' \
--form 'fromDate="<Enter_from_date>"' \
--form 'toDate="<Enter_to_date>"'

Success Response Sample

The following is a sample of a success response from the API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "name": true,
        "from-date": true,
        "evn-id": true,
        "amount": false,
        "address": true,
        "to-date": true
    },
    "requestId": "<Request_ID>"
}

Success Response Details

Parameter	Type	Description
result.name	boolean	Indicates if the name on the bill matches the user-entered name
result.from-date	boolean	Indicates if the "from date" on the bill matches the user-entered "from date"
result.evn-id	boolean	Indicates if the EVN ID on the bill matches the user-entered EVN ID
result.amount	boolean	Indicates if the amount on the bill matches the user-entered amount
result.address	boolean	Indicates if the address on the bill matches the user-entered address
result.to-date	boolean	Indicates if the "to date" on the bill matches the user-entered "to date"

Failure Response Sample

The following is a sample response when no matching record is found against the input parameter.

{
	"status": "failure",
	"statusCode": 400,
"error": "API call requires atlest one input image"
}

Error Response Samples

Rate Limit Exceeded

{
  	"status": "failure",
  	"statusCode": 429,
  	"error": "Rate limit exceeded"
}

Internal Server Error

The following is a sample response for a server error:

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Error Description
400	This error is returned when 'image' is not sent in the API call	This error is returned when more than 2 images are sent in the API call
400	API call handles only upto 2 images	This error is returned when more than 2 images are sent in the API call
400	image size cannot be greater than 6MB	The maximum size of input image is 6MB. Crossing this will result in this error
429	Rate limit exceeded	You have exceeded the configured limit on the number of transactions permitted in a minute. Please contact the HyperVerge team for resolution
500/501	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	Server busy	Please contact the HyperVerge team for resolution